﻿#region License
/* ---------------------------------------------------------------- *
 *
 * This file is part of the Xcoordination Application Space
 * ("XcoAppSpace") http://www.xcoordination.com
 *
 * Copyright (C) 2009 Xcoordination http://www.xcoordination.com
 *
 * XcoAppSpace is free software; you can redistribute it and/or
 * modify it under the terms of version 2 of the GNU General
 * Public License as published by the Free Software Foundation.
 *
 * XcoAppSpace is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see http://www.gnu.org/licenses/
 * or write to the Free Software Foundation, Inc., 51 Franklin
 * Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * ---------------------------------------------------------------- */
#endregion
#if !MF
using System;
#if!MF
using XcoAppSpaces.Contracts.Service;
#endif
using Microsoft.Ccr.Core;
using System.Net;

namespace XcoAppSpaces.Contracts.Security
{
	/// <summary>
	/// Interface 
	/// </summary>
	public interface IXcoSecurityService
#if !MF 
        :  IXcoStatefulService
#endif
	{
		/// <summary>
		/// Gets xco client credentials from a given credentials object and for the given address, that can be 
		/// transfered to a remote space and used to authenticate a user at a remote space.
		/// </summary>
		/// <param name="credentials">The ICredentials object where to read the credentials from.</param>
		/// <param name="address">The address for which the credentials are needed.</param>
		/// <returns>A new IXcoClientCredentials instance containing the needed authentication information.</returns>
		IXcoClientCredentials GetClientCredentials(ICredentials credentials, string address);

		/// <summary>
		/// Authenticates access for the given user to the space. It is checked if the username and password
		/// are valid. A sessionID is generated if authentication is successful. If the user already has an open
		/// session, the id of the existing session is returned.
		/// </summary>
		/// <param name="address">The host address of the user.</param>
		/// <param name="credentials">The credentials of the user.</param>
		/// <returns>The result of the authentication, including the Guid of the user session if it was successful.</returns>
		XcoAuthenticationResult Authenticate(string address, IXcoClientCredentials credentials);

		/// <summary>
		/// Authorizes access for the user of the given session to the given worker. Authorization is successful
		/// if the user is allowed to access at least one port of the worker.
		/// </summary>
		/// <param name="address">The host address of the user.</param>
		/// <param name="sessionID">The sessionID of the user (that was generated during user authentication).</param>
		/// <param name="worker">The worker instance.</param>
		/// <returns>True if the user is authorized to access the worker.</returns>
		bool Authorize(string address, Guid sessionID, IPort worker);

		/// <summary>
		/// Checks if certain port of a worker can be accessed by a specific session. An XcoSecurityException is thrown
		/// if the operation is not permitted.
		/// </summary>
		/// <param name="worker">The worker that should be accessed.</param>
		/// <param name="message">The message that should be posted to the worker.</param>
		/// <param name="address">The address ot the sender of the message.</param>
		/// <param name="sessionID">The ID of the session that the sender uses for communication.</param>
		void CheckPermission(IPort worker, object message, string address, Guid sessionID);

		/// <summary>
		/// Gets the username for the given session id.
		/// </summary>
		/// <param name="sessionID">The id of the session for which the user should be retrieved.</param>
		/// <returns>The username for the given session, or null if no user is applied to this session.</returns>
		string GetUsername(Guid sessionID);
	}
}
#endif
